URLSimpleDownload

Downloads data synchronously from a URL.

OSStatus URLSimpleDownload (
                     const char* url,
                     FSSpec* destination,
                     Handle destinationHandle,
                     URLOpenFlags openFlags,
                     URLSystemEventProcPtr eventProc,
                     void* userContext);

url

A pointer to the URL from which data is to be downloaded.

destination

A pointer to a structure of type FSSpec that describes the file or directory into which data is to be downloaded, or NULL , in which case you must supply a value for destinationHandle that is a valid handle.

If destination is of type FSSpec , but it does not specify the name of a file or directory, the name of the file or directory specified by the URL is used. If that file or directory already exists and you do not specify kURLReplaceExistingFlag in the openFlags parameter, URLSimpleDownload creates a new file or directory whose name has a number appended before the extension. For example, if the URL specifies a file named file.txt , URLSimpleDownload changes the filename to file1.txt .

For more information about the FSSpec structure, see Inside Macintosh: Files .

destinationHandle

A handle for downloading data into memory, or NULL , in which case you must specify a value for destination that is a valid file specification. Before calling URLSimpleDownload , create a handle of zero size.

openFlags

A value of type URLOpenFlags that specifies download options, such as expanding a file or replacing a file if its filename is already in use. The following constants can be used to specify download options:

kURLReplaceExistingFlag kURLExpandFile Flag kURLDisplayProgressFlag kURLDisplayAuthFlag kURLIsDirectoryHintFlag kURLDoNotTryAnonymousFlag kURLDirectoryListingFlag

See Open Flag Constants for descriptions of these constants.

eventProc

A value of type URLSystemEventProcPtr that points to an application-defined system event callback routine System Event Callback Routine that the URL Access Manager calls to communicate system events to your application during the download process. If your application requests the display of a progress indicator or authentication dialog box, these items appear in a movable modal dialog box.

The value of eventProc can be NULL , in which case your application will not be informed of system events. If your application requests the display of a progress indicator or authentication dialog box,these items appear in a non-movable modal dialog box.

userContext

An untyped pointer to arbitrary data that the URL Access Manager passes to the application-defined system event callback routine specified by eventProc . Your application can use userContext to associate a callback with a particular call to URLSimpleDownload .

function result

A result code. For a list of possible result codes, see Result Codes .

DISCUSSION

TheURLSimpleDownload function downloads data synchronously from a specified URL to a specified file or directory and does not return until the download is complete. The URLSimpleDownload function yields time to other threads. Your application should call URLSimpleDownload from a thread other than the main thread so that other processes have time to run.

If you want a progress indicator to be displayed during the download, specify kURLDisplayProgressFlag in the openFlags parameter. The URL Access Manager uses a modal dialog box to display the progress indicator.

If your application has multiple threads, it can call URLSimpleDownload multiple times, but if it calls URLSimpleDownload with kURLDisplayProgressFlag set in openFlags when the URL Access Manager is already displaying a modal dialog box, URLSimpleDownload returns the error kURLProgessAlreadyDisplayedError .

If the url parameter specifies a file, the file is downloadedregardless of whether kURLDirectoryListingFlag or KURLIsDirectoryHintFlag is set in the openFlags parameter.

When URLSimpleDownload downloads data from a file:/// URL, the data fork is downloaded but the resource fork is not downloaded.

Call URLDownload if you need to set properties or URLOpen if you need to control the download process.